Amiga Collections: Camelot/Camelot 059 (1989-12)(Swedish User Group of Amiga)(SE)(PD)[WB].zip/Camelot 059 (1989-12)(Swedish User Group of Amiga)(SE)(PD)[WB].adf/Xoper/Xoper.doc

Text File | 1989-11-15 | 21KB | 557 lines

                 Xoper V2.1

            Copyright (c) Werner Gunther 1989

Xoper is a freeware program to display and to control system activity.
Permition is granted to freely distribute this program.

--------------------------------------------------------------------------
Changes in V1.2:
New commands: Snoop, Capture, ClrCool, ClrWarm, ClrCold.
Added        : CPU usage by task.

Cancel command has been rewritten, some minor bugs removed.
---------------------------------------------------------------------------
Changes in V1.3:
New commands: [S]=Stack usage, Sort, Hide, Hidden, Header, Window,
          InputHandler.
Added        : Support of startup-scripts, I/O Interrupts/second, 'Kill' an
          alias for 'Cancel'.
Some BIG bugs have been removed: The port-display used to GURU if more than
32 Ports did exist. The Cli Xoper has been started did act like having a
priority of 128. Unlock didn't unlock sometimes, the interrupt/priority
field did contain rubbish, Currentdir didn't examine all Processes.
There were some more, minor bugs, all (hopefully) removed.
---------------------------------------------------------------------------
Changes in V1.3b:
New commands: [C] information on CLI-Tasks.
Added        : 'Time 0' stops any update, System-Requesters are now handeled
          correctly (affects 'Kill' and 'Closewindow').
---------------------------------------------------------------------------
Changes in V2.0:
The 'user interface' (what user interface ?) has been rewritten from
scratch, and a small iconify routine has been added. To customize the whole
thing a little bit, there are a few new commands:
 MinimumChars, HistoryLines, ShowHistory, KillHistory, OutputLines,
IconifyOff, BackDropIcon, UseScreen, UseWindow.
Other new commands include:
TimerIO, RemResident, Repeat, TrapGuru, Setfont, DiskChange, Alias,
SaveOutput.
Addresses are now shown as 32-Bit values for 68020 compatibility. The 'More'
command is obsolete and has been removed. The 'interrupt list' has two new
fields. 'Time' w/o parameters shows current setting. 'display commands'
separated by blanks will display the lists one by one, instead of
displaying them all at once.
---------------------------------------------------------------------------
Changes in V2.1:
Mostly bug fixes:
 KS1.3 dependancy removed. Using UseScreen in the startup file could crash
the program if started with the -b flag. The S (stack) command wasn't
robust enought. Some strangness in the 'KILL' routine have been removed.
The iconizing routine couldn't distinguish between multiple drags and
doubleclicks.
Added: SetFKeys, Time accepts values < 1, 'Windows' shows the owner task (if
available). The task display shows the name of the loaded command
(enclosed in '[]') instead of the name, if the task is a CLI, 'CLICmd'
toggles this feature on/off. Commandline completion using <tab>.

A new program 'KillXoper' has been added to the distribution to remove
Xoper from memory in case it loops or freezes (I hope it won't be needed).
---------------------------------------------------------------------------

Starting Xoper from CLI:

Xoper [T] [F] [S] [L] [D] [R] [E] [M] [P] [I] [C]

These parameters are described below. For all those who like long
Startup-Sequences, overcrowded memory and hot-keys enter

Xoper -b

This will install Xoper in background waiting for LeftAmiga-RightAmiga-X
to pop up. In both cases you don't have to RUN or RUNBACK Xoper, it will
always create its own process.

At startup Xoper loads and executes a file named S:Xoper.Startup if such a
file is available. This startup-script is used to set default values, the
window size or the initial default list to be displayed. The Xoper-window
will only be opened after the startup-script has been processed. Look at the
end of the document for a sample startup file.

Xoper Window:
-------------
 The window (or screen if you request one) is devided into two sections: a
very small input line on the bottom and a large output area on the top. If
the output exceeds the size of the window you may scroll or 'page' through
the text using the num-pad keys:

A1000  A2000/A500
  7    Home        Top of display
  1    End        Bottom
  9    Pg Up        one page up
  3    Pg Dn        one page down
  8    Up Arrow    one line up
  2    Down Arrow    one line down
  4    Left Arrow    one page left
  6    Right Arrow    one page right

 The input section has some line editing facilities and a history buffer
contollable with the following keys (similar to NewCon and ConMan):

Cursor left        cursor one character left
Shift  left        cursor to the start of the next word
Cursor right        one character right
Shift  right        previous word
Cursor Up        previous line in history buffer
Shift  Up        top of buffer
Cursor Down        next line in history buffer
Shift  Down        bottom of buffer
DEL            DEL
BS            backspace
Ctrl   X        delete line
Ctrl   Y        delete EOL
Ins   (numpad '0')      toggles insert mode (default is 'on')
Del   (numpad '.')      same as DEL

ESC            moves the input area from the bottom into the
            output section. Entering a command here (i.e
            overwiting an output line), will cause Xoper to add
            the address of that node to your command line.
            Example: Show the hunks of a 'File.System' process:
            type 'T' to get a list of all tasks, press <esc>,
            move the cursor to the line displaying the
            File.System process and type 'Hunks <enter>'. Press
            <enter> once more to return to the usual Xoper
            display.
Help            displays a help panel.
TAB            Command line completion.
            Example: press <c>, hit <tab> several times.

The Xoper window has, beside the usual closewindow and depth-arrange
gadgets, a custom gadget on its title bar, used to iconify Xoper. The icon
may be moved anywhere on the screen just by dragging it, double clicking
the icon will restart the program. The window itself is a simple_refresh
window, so it may look a little bit sluggish when it needs a refresh.

Xoper Commands:
---------------

 Commands are entered in the command line at the bottom of the window,
these are divided into two groups:

Display commands: These are always single character entries and may be
specified in any order, upper or lower case, after the prompt or from CLI
as parameters. If more than one list has to be displayed, you may enter
several commands in one line. Separating them with blanks display the lists
one by one instead of showing them all at once.

T = Tasks (Default if Xoper is called without parameters)
Task node (HEX), Display type, status, priority (decimal), CPU usage
(percent), processnumber for Dos-Processes (decimal), taskname (or the
name of the loaded command, if a CLI process. The loaded command name
is enclosed in '[]').

F = Task Flags
Task node (HEX), Allocated Signals (HEX), Signals the Task is waiting for
(HEX), Signals received (HEX), Address of the next instruction to be
executed (HEX).

C = Cli Commands
Task node (HEX), Type (interactive/batch), Mode (Background/Foreground),
CLI number, CLI name, program it executes.

L = Libraries
Base address (HEX), open count (decimal), version (decimal), revision
(decimal), flags (binary), libraryname.

D = Devices
Base address (HEX), open count (decimal), version (decimal), revision
(decimal), flags (binary), devicename.

E = Resident (sorry)
Base address (HEX), priority (decimal), flags (binary), version
(decimal), type, name.

R = Resources
Base address (HEX), open count (decimal), version (decimal), revision
(decimal), flags (binary), resource name.

M = Memory
Lower and upper bounds (HEX), bytes free (decimal), attributes, priority
(decimal), hunk name.

P = Ports
Node address (HEX), portname, flags, signal bit (decimal), queue length
[number of messages] (decimal), taskname.

I = Interrupts
Node address (HEX), pointer to interrupt data (HEX), pointer to interrupt
code (HEX), priority (decimal),[T]ype ([S]erver/[H]andler), [S]tate
([E]nabled/[D]isabled), type (interrupt queue the interrupt belongs to),
interrupt name.

S = Stack
Lower limit of the stack, stack size, currently used stacksize, taskname.
If you want to minimize your stack using this utility, please note that
DOS-functions use 1500 Bytes at the bottom of the Stack frame for their own
purposes and note that the stacksize is only checked one time per second by
this command.

H = Help ( or ?)
Show a list of commands.

; = NOP
Skip this line (used for remarks in a script file)

Q = Quit
Same as QUIT (see below).

Example: Entering TPM would display Tasks, Ports and Memory. The display
would be updated after a few seconds (5 by default, may be changed
anytime, see below.)

Other commands that do not display EXEC lists:
These commands may be entered upper or lower case. Parameters enclosed
in '<>' must be, enclosed in '[]' may be specified. Names are usually
entered as ascii strings, it can however happen that two or more nodes of
the same name exist. On tasks you may specify the DOS-Processnumber to
sort them out. If everything fails, you can enter the Node-Address with a
leading '$'. This address will be checked first before the command is being
executed. If the check fails, you'll get an error message or a warning or
a prompt, depending on what went wrong. Names are always the last parameter
to enter. This may seem strange, but it is the simplest way to get rid of
embedded blanks.

Time <seconds>
Set time between updates. Minimum is 0.1 seconds, maximum is 255.9, default
is 5 seconds. Time 0 stops automatic update and waits for a keypress. Values
 < 0.5 are not recommended.
Example: Time 1.5

Taskpri <priority> [processnumber] <taskname>
Change the priority of a task. Values may range from -127 to 127, better
use values between -5 and 5.
Example: Taskpri 1 New Cli

Mypri <priority>
Shortcut for "Taskpri Xoper <priority>"
Example: Mypri 2

Pri <priority> <nodename>
Change the priority of any other node. This command does not work for Tasks.
If the specified node has been found, the entire list the node belongs to
will be resorted.
Example: Pri 1 Chip Memory      (try to allocate memory in CHIP first)

Break [processnumber] <taskname>
Set break signals. Useful for tasks running in background or from Workbench.
Example: Break 3 New CLI

Hunks [processnumber] <processname>
Show location, BCPL-Pointers and length of memory blocks the process uses.
Example: Hunks RAM

Snoop [processnumber] <taskname>
Track memory allocation/deallocation of a task. Press break (CTRL-C) to
stop. List includes: action (alloc/free), memory requirements (CHIP/ FAST/
PUBLIC etc), memory size, memory location (start, end) and the address from
where AllocMem() was called.

Files
List lock, access, size and name of open files.

Locks
List any lock.
BUG: Trying to lock the Volume "RAM Disk" crashes the machine sometimes. If
a Volume "RAM Disk" is found it will be replaced by the devicename "RAM:"
(this has been fixed on WB 1.3). Make sure you don't have a disk labeled
"RAM Disk" or you'll never see its locks:-)

Currentdir
List current directory settings of all processes.

Devices
List name,heads,sectors,tracks,startup-buffers and handler-process of every
DOS-device.

Inputhandler
Display node, priority and name (if any) of the input-handlers currently in
use.

Capture
Show vectors controlling the reset, i.e. CoolCapture, ColdCapture and
WarmCapture pointers, KickMem allocations. Useful when searching
for Viruses, but remember that the RAD: device in 1.3 uses the KickMem
pointer to recover from a reset.

ClrCool
ClrCold
ClrWarm
Clear one of those pointers.

TimerIO
Display pending timer requests. It shows the address of the
IORequest-structure, the unit (MICROHZ or VBLANK), the time to complete (up
to 255 secs) and the task submitting the request.

RemResident <resident module name>
Kicks the resident module out of the ResModules-List. It does not free the
module itself, but only makes sure it won't be reactivated during the next
reset. Removing a ROM-based module does not have any effect.

Repeat <Command string>
Repeats the command string at the current refresh rate (see 'Time').
However, commands not producing any output won't be repeated, but only
executed once. Press <enter> to stop.
Example: Time 1
     Repeat TimerIO

TrapGuru
Activates a trap handler similar to GOMF. It only works with a 68000
processor, as it relys on a specified stack frame (at least I think so,
couldn't check it out). If an exception occurs (i.e. GURU) Xoper will
stop (or popup, if running in background) and display some information
about what happened (the taskname causing the error, its program counter,
the alert number etc.) and you'll be asked if you want to (K)ill the task
or (I)gnore the exception. Choosing (i)gnore will do nothing at all if the
erroneous program was a process (as it will stop itself displaying a
'Task held...' requester), but force a task to execute a 'Wait(0L)' (i.e.
wait forever) as tasks do directly display an alert box.

Alias <AliasName> <CommandName>
Defines a new name to be used along with the original command name. The new
name should not contain any blanks.
Example: Alias ih InputHandler

SetFKey <key number> <string>
Assign a string to a funktion key. 'Key number' is a value between 1-20,
10-20 denotes shifted keys. Use '^' to simulate a <return> and '_' for
space (the parser strips leading/trailing blanks).
Example: SetFKey 1 Hunks^
     enter t <return>, press <escape>, move the cursor to a process,
     press F1

Lockdrive <drivename:>
Prevent DOS, Workbench and Disk-Validator from cluttering on the drive.
This command isn't very useful, but I needed it myself. Please note that
the drivename is case sensitive and has to end with a ':'.

Freedrive <drivename:>
Re-enable a drive.

DiskChange
Show all installed diskchange interrupts. It displays the node, data and
code fields of the interrupt, the device it is attached to (df0:-df3:) and
the task which added the interrupt (if available). The main purpose for
this command is to check for a virus, as the diskchange interrupt is a
wonderful place to install them.

Windows
List address and title of all windows.

Screens
List address and title of screens.

Fonts
List address,height,width,type,fist character and last character of all
loaded fonts.

Windowfonts
List Windows and associated fonts.

SetFont [size] <fontname> <window>
Change the default font of a window. To avoid confusion, you should use a
font with the same font size as the original font, as many programs rely on
the point size.
Example: Windows
     Press <esc>, move the cursor to the Xoper window line and type
     Setfont diamond.font
     (now you know what I mean by 'relying on a font size' :-))

Freeze [processnumber] <taskname>
Halt a Task. The task should be READY or WAITING. Frozen tasks are queued in
a new list called FROZEN. When you leave Xoper, halted Task will be
released.
Example: Freeze Killer Graphics Task

Warm [processnum] <taskname>
Restart a halted Task. Task must be FROZEN.
Example: Warm Killer Graphics Task

Hide <taskname>
The task-list tend to be longer than the window size. You may inhibit the
output of some tasks you are not interested in using his command.
Example: Hide trackdisk.device

Hidden
Turn those hidden Tasks back on. It is actually a toggle.

Header
Toggle the (rather long) header on the task display on/off.

Sort
The tasks listing is sorted (on V1.3 and above) to avoid 'jumping' of the
display. Sort toggles this feature on/off. (Stupid command, but was easy
to implement).

CLICmd
Toggles between showing the loaded command and the taskname of CLI processes
in the tasks listing.

Info <librarynode | devicenode>
Show additional information stored in the lib_IdString field.
Example: Info arp.library

Openlib <libraryname>
Open a library. This is useful if you don't want a specified library being
'flushed' out.
Example: Openlib arp.library

Clear [longword]
Fill unused memory chunks with pattern, default is 0. Handy for debuggers.
Example: Clear $66726565

Flush
Clean up memory, flush unused libraries, devices and fonts.

Lastalert
Show last Guru Meditation code or rubbish.

Usage
Toggle CPUSE field on the task display between usage relative to all
possible dispatches and usage relative to actually dispatched tasks.
Ahem...not very clear I think. Well, let me try again...
If you add all CPUSE fields together you get 100 % (more or less 1%). After
entering "Usage" adding the fields together will give you the same value as
shown in the 'CPU Activity field'. (I HATE having to write docs)

Taskports
Disable / enable a listing of taskports if ports are displayed.

Window <leftedge> [toptedge [width [height]]]
Works only on script files. Defines the window to be opened.
Example: Window 0 0 550 190

HistoryLines <number of lines>
Set the maximum number of input lines the history buffer should hold.
Default is 10 lines.

MinimumChars <number of characters>
Set the minimum number of characters an inputline should have to be added to
the history buffer.
Default is 2 characters.

ShowHistory
Show the history buffer. (quite useless, I know)

KillHistory
Delete all lines from the history buffer. (still useless)

OutputLines <number of lines>
Set the maximum number of lines the output buffer may hold. If the buffer
overflows, a line from the top of the buffer will be deleted for each new
line.
The default value is 500, using a maximum of 500 * 104 = 52000 bytes.

SaveOutput <filename>
Write the contents of the output buffer to a file.

IconifyOff
Turns the iconifying routine off, freeing all memory associated with its
code and image.

BackDropIcon
Puts the Xoper icon behind all other windows, instead of creating it on top
of them.

UseScreen
Opens Xoper on a screen. The new screen will take its data (width, colors,
viewmodes etc.) from the Workbench screen and open a borderless backdrop
window on it.

UseWindow
Opens Xoper on a window.

Quit or just Q
Exit Xoper. If Xoper was started with '-b' or if 'Hold' was specified it
will stay in background waiting for LeftAmiga-RightAmiga-X.

Hold
Exit Xoper but install a key-handler and stay in background. Window
settings and display commands are saved.

Exit
Clean up and quit.

!!!! WARNING: The next few commands are dangerous and 'dirty' !!!!!
!!!!!!!!!!!! don't use them if not strictly necessary !!!!!!!!!!!!!

Kill [processnumber] <taskname>
Kill a task or a process. If the task has been called from CLI, the Task
itself and the CLI will be killed. Hunks, Windows, Screens  and the
teminal-window will be freed. Simple tasks are just RemTask()'ed. If it is
not a CLI Task you'll be asked if it is a Workbench task, if the answer is
'Yes' unloading will be done by the Workbench. If not, you will be prompted
if Xoper should unload the code. Enter 'No' if you don't know how the task
has been started. A good example for tasks that should NEVER be unloaded are
program started by ARP'S ASyncRun (or ARun).

Closewindow <title>
Closes a Window. Please, use it only if the corresponding Task has been
'Cancel'ed. Use the Window-Structure address if the window has no name.

Closescreen <title>
same as above, but for screens.

Unlock <lock (BPTR)>
Unlock a file.

Closelib <libraryname>
This is exactly the same as CloseLibrary().

CD [processnumber] <processname>
Change the current directory of a process. You are prompted if the old
directory lock should be unlocked.

Signal <mask> [processnumber] <taskname>
Set any task-signal. Mask is a hexadecimal value with or w/o leading '$'.
See task's SIGWAIT field for sensible values. Tasks normally do not wait for
signals only, but for messages, that's why this command may not have the
desired effect, but it is quite useful for tasks hanging around and waiting
for events that may never happen. Warning: Using Signal without any
knowledge about what you are going to signal may cause a system-crash!
Example: Signal 10000000 PopCLI III

----------------------------------------------------------------------------
;Sample Startup Script (to be placed in s:Xoper.Startup)
;
; Window definition on a overscanned + PAL Workbench screen
Window 122 0 550 230
;
;don't display some Tasks
;
Hide CON
Hide trackdisk.device
;
;but turn them on on Startup
;
Hidden
;
;Change the default list to Ports
;
P
;don't display any prompt if the window is full
More
----------------------------------------------------------------------------
Please send flames, bug reports and especially a list of features you would
like to have included in the next version to

 Werner Gunther
 Wingertspfad 12
 D 6900 Heidelberg
 (Germany)

or to my EMAIL address for a fast response:

 [e-mail]